NetCloak provides new commands that you can incorporate in your HTML pages. NetCloak commands allow you to display information specific to the client or the server at the time the document is being processed, and also allow you to show and hide any individual portion of your document.
While NetCloak commands are not standard HTML tags, they are processed entirely on your Web server, so they work with any Web browser.
Once you have installed NetCloak you may immediately begin to compose HTML documents using NetCloak commands. We strongly recommend that you be completely comfortable writing HTML pages before you start using NetCloak.
If you are not familiar with HTML you can get more information from a variety of sources on the Web. A good place to start is Yahoo (www.yahoo.com). There you will find a long list of HTML primers and guides. Once you are familiar with HTML, adding NetCloak features to your pages is easy.
NetCloak's INSERT commands will place dynamic information into your documents supplied by the browser, your server or your users themselves.
For example, to add the current time and date, simply place the commands <INSERT_TIME> and <INSERT_DATE> in the text of your document, as in:
It is <INSERT_TIME> on <INSERT_DATE>.
To add a page counter, use the <INSERT_COUNT> command:
This page has been hit <INSERT_COUNT> times.
Most commands that insert information into a page begin with "INSERT", but there are a number of commands such as MACRO and EXEC_CGI which also insert text into a page.
NetCloak can do a lot more than simply inserting text, but the simple INSERT commands are a great way to get started. Once you are feeling comfortable inserting information into your pages, you'll be ready to move on to SHOW and HIDE commands.
To understand building completely dynamic pages, think of your document as a stream of information being sent through a faucet (your Web server) to the client. NetCloak allows you to turn off (HIDE) and turn on (SHOW) this stream at will.
For example, the following cloaked text:
This is a <HIDE> trivial <SHOW> test.
Would appear on a web browser as:
This is a test.
All of the NetCloak "HIDE" commands hide text from the user accessing the page, depending on some variable, essentially turning the stream of text off for that client. "SHOW" commands are used to conditionally turn the stream back on, allowing the user to see the text that follows.
The basic, unconditional HIDE and SHOW commands are very simple, but not very useful by themselves. There are many other NetCloak commands which allow turning the stream off and on conditionally. For example, the HIDE_TIME command will turn the stream off based on the time of day, and the SHOW_RANDOM command will show text based on a random number. These commands are where the real power of NetCloak lies.
To use a conditional command, you must of course specify a condition. The HIDE_TIME command doesn't make sense until you specify a time for something to be hidden. For example:
<HIDE_TIME 10> This will hide text following the command during the 10 o'clock hour.
Conditional hide and show commands also allow more than one parameter to be specified. For example, to show text to visitors on the weekend, you would use the command:
<SHOW_DAY Sat Sun>
See the Commands section of this Guide which lists all of the NetCloak commands and explains how each of them works.
Turning off and turning on (hiding and showing) portions of your HTML document is not limited only to text. Hyperlinks which point to other pages, IMG SRC tags etc., can be turned off and turned on as well. All this gives you complete control over how your document looks and behaves in a variety of situations.
All NetCloak commands follow the same rules of syntax. Like HTML tags, every command must begin with an open angle-bracket ("<"), followed immediately by the command name. The command name is not case-sensitive, but for good form and recognizability, our examples and User's Guide show commands in all caps.
Following the command name may be one or more parameters and a closing angle-bracket (">"). While the parameters may be optional, the closing bracket is required. Parameters may be separated by one or more spaces, tab characters or line breaks.
Quotation Marks
In most cases, parameters can be placed in quotes , but quotes are not required. For example:
<SHOW_CLIENT "mozilla">
is functionally equivalent to:
<SHOW_CLIENT mozilla>
Using quotes, however, allows you to include spaces within a parameter. For example:
<SHOW_CLIENT "mozilla 3.0">
is very different from:
<SHOW_CLIENT mozilla 3.0>
The first case looks for the client "mozilla 3.0", but the second will recognize either client names that include "mozilla" or "3.0". This is because the space between "mozilla" and "3.0" is interpreted by NetCloak as a delimiter between parameters instead of the space that appears in the browser name.
When a parameter is set inside quotes, you must use two double-quote characters to specify a quote, so that NetCloak does not interpret the quote character as the end of the parameter. For example:
<HIDE_VARIABLE SomeVar "He said ""moof""!">
This command would look for the string "He said "moof"!", because NetCloak interprets the two double-quote marks as a quote instead of the end of the parameter.
Quotes may not be used around variable names. If a variable name is enclosed in quotes it will be interpreted as a text string and not a variable name. For example, if you have a local variable called "TestVar" that is set to the value "Moof", you might do something like this:
<SET_LOCAL NewVar = "TestVar" & " Says the Dogcow"> <INSERT_LOCAL NewVar>
This would display:
TestVar Says the Dogcow
What is really desired is this:
<SET_LOCAL NewVar = TestVar & " Says the Dogcow"> <INSERT_LOCAL NewVar>
Resulting in:
Moof Says the Dogcow
In the first example TestVar is specified as a string and NetCloak inserts it accordingly. In the second, NetCloak recognizes that TestVar may be some other kind of entity, and evaluates it correctly.
Specifying Repeating Parameters
Most SHOW and HIDE commands which have only one type of parameter will accept multiple parameters in a series, and show or hide if any of them are matched. For example, the SHOW_DAY command only accepts a day as a parameter and so allows multiple days to be specified, as in:
<SHOW_DAY SAT SUN>
This will show text on either Saturday or Sunday.
Specifying Optional Parameters
Commands which accept more than one type of parameter only allow one of each. The parameters are recognized by the order in which they appear, so ordering must always be closely followed. Some or all parameters may be optional, but to use the second or later parameters, all of the preceding parameters must be specified.
For example, the INSERT_DATE command allows an optional offset and an optional format parameter. The command may be used without any parameters, or with only an offset parameter: If multiple parameters are used, they must be included in order:
<INSERT_DATE +24 SHORT>
<INSERT_DATE SHORT +24>
Of the two commands above, only the first will work correctly because the parameters are in the correct order.
For ease of use, some commands allow the second or later parameter without using a value for the preceding parameters. In most cases, however, if you want to specify an optional parameter you must be careful to include all of them. For example:
<INSERT_DATE SHORT>
This will insert the date in short format, as expected. However, if you intended to use INSERT_COUNTDOWN with a different label for "Days" you might try using:
<INSERT_COUNTDOWN_D 1/1/00 "x24 hours">
This would not work as intended. NetCloak will interpret "x24 hours" as the label for weeks, instead of days because the parameters are only interpreted in order. To use the second or later parameter in a command without specifying the preceding parameters, use a pair of quotation marks as a placeholder. The correct command for the previous INSERT_COUNTDOWN example would be:
<INSERT_COUNTDOWN_D 1/1/00 "" "x24 hours">
The Commands section specifies the order of the parameters, whether the order is required and which parameters are optional for each command.
Parameter Wildcards
Many NetCloak commands allow you to specify an asterisk in place of a single character in a parameter, where the asterisk will match any character. This is commonly known as a wildcard.
For example, the following command will display the line following it on any day starting with "T".
<HIDE><SHOW_DAY T**> Today is Tuesday or Thursday
Note that two asterisks are required, since each represents a single character and the SHOW_DAY command requires the first three letters of the day as a parameter.
INSERT commands do not allow wildcards. In most cases, a wildcard would not make sense for these commands. Wildcards are similarly disallowed in SHOW and HIDE commands which take numbers as a parameter, including COUNT, RANDOM and SAMERAND commands, or commands which take a date or a time as a parameter. The MACRO and EXEC_CGI commands do not allow wildcards in any of their parameters.
Variable commands (SHOW and HIDE LOCAL, GLOBAL or VARIABLE) will accept wildcards in parameters, however, you must use them carefully because an asterisk is also used as the multiplication operator. Enclosing parameters in quotation marks will generally prevent this type of problem, as well as making the commands easier to read. Wildcards do not work in variable values, however.
<SET_VARIABLE myVar "bob"> <HIDE><SHOW_VARIABLE myVar "b*b"> This will be shown.
This example will show the text if the value of the variable is "bob", "bib" or any other three letter combination starting and ending with "b". The opposite, where the wildcard is in the variable, will not work.
<SET_VARIABLE myVar "b*b"> <HIDE><SHOW_VARIABLE myVar "bob"> This will not be shown!
The example above will not show the text even though the wildcard in "b*b" should match "bob".
Included with NetCloak is a utility to make it easier to use NetCloak commands without having to memorize exact syntax or look them up the in the User's Guide. TagBuilder displays a floating window listing all of the NetCloak commands and allows you to drag and drop them into your documents, no matter what editor you are using. It also has a help window which will display syntax and a brief explanation of each command.
TagBuilder is not required to use NetCloak, but makes it much faster and easier to get started and provides a handy reference any time.
It is extremely important to remember that the SHOW command will never cause a HIDE and vice-versa. For instance <SHOW_DOMAIN 123.45> will turn showing on for those in the domain "123.45", but it will not hide text from those outside the domain. To do this, you must precede the SHOW command with an unconditional HIDE.
Think of the text of your document as a stream of text flowing through a faucet. When you use a conditional SHOW command, you are saying "turn the faucet on if this is true" but you are not saying "turn the faucet off if it is not true". The same rule applies to HIDE.
What this allows you to do is use the commands in a cumulative way. This is best seen by an example:
<SHOW> Here is the first line, visible to everyone.
<HIDE_DOMAIN some.domain> This is hidden from users in "some.domain".
<HIDE_DOMAIN another.domain> Hidden from "another.domain" AND "some.domain".
<SHOW> This last line can be seen by everyone.
If we had wanted the sixth line to be hidden ONLY from "another.domain", the HTML would have been...
<SHOW> Here is the first line, visible to everyone.
<HIDE_DOMAIN some.domain> This is hidden from users on "some.domain".
<SHOW><HIDE_DOMAIN another.domain> Hidden from "another.domain" ONLY.
<SHOW> This last line can be seen by everyone.
The extra SHOW command "turns the HTML on" before the HIDE command shuts it back of for the desired users. This can get a little confusing, but there is a simple rule.
When you want to specify "Hide only from ...", use:
<SHOW><HIDE ...>
And when you want to specify "Show only to...", use:
<HIDE><SHOW ...>
This is very important, as the next example shows:
<SHOW> This line is viewable by the world!
<SHOW_DAY SAT SUN> This line is ALSO visible to the world.
In this example, since everyone could already view the HTML text, SHOW_DAY didn't do anything. To do what we want, to show the line only on the weekends, this example should be:
<SHOW> This line is viewable by the world!
<HIDE><SHOW_DAY SAT SUN> This line is visible ONLY on the weekend.
<SHOW>
By hiding first, we block access from everyone and then let people see the text ONLY when we want.
Why does NetCloak work like this?
Because, despite the fact that it takes a little getting used to, it gives you a lot more flexibility. For example, let's say you wanted to have a section of your document available only to your company all the time. The rest of the world could see the section during non-business hours only. In this case, you could do this:
<SHOW> This line is always available to everyone
<HIDE> <SHOW_DOMAIN my.local.domain> <SHOW_DAY SAT SUN> <SHOW_TIME 19 20 21 22 23 00 01 02 03 04 05> This line is available to my local users all the time,
and to the rest of the world during off hours.
This example first hides the HTML text, then turns viewing back on for each specific case.
As you've seen, you can show and hide portions of your pages based on a wide range of variables within NetCloak. This gives you a great deal of flexibility and you can create fairly complex conditions in which each part of a page will be visible. There is, however, an additional variation available in every conditional SHOW and HIDE command which allows you to show or hide in all cases except when the condition is true.
For example, assume you wanted to have a portion of your page visible during the normal business week, Monday through Friday. You could write...
<HIDE><SHOW_DAY MON TUE WED THU FRI> This text is visible during the week only.
But there is another way to make this same statement. Instead of saying "show text on Monday, Tuesday, Wednesday, Thursday, and Friday" (as we did above), you could say "show text on all days except Saturday and Sunday". To do this, you would use:
<HIDE><SHOW_DAY# SAT SUN> This text is visible during the week only.
To be honest, this isn't really much easier, at least in this example. But what if you wanted to show text based on SHOW_DOMAIN to all users except those at a certain address. You certainly wouldn't want to list every domain on the Internet, so <SHOW_DOMAIN# 192.1.2.3> could be very handy when you want to show a section of your page to everyone except "192.1.2.3".
Of course, you could, in many cases, also use the HIDE commands instead. For example, the "192.1.2.3" example could have been written as:
<SHOW><HIDE_DOMAIN 192.1.2.3>
When building more complicated conditionals, using "HIDE" in place of "SHOW except" is no longer an option. Remember that SHOW and HIDE are fundamentally different in that SHOW will never "hide" text, and HIDE will never cause text to be seen. So, if we wanted to have a portion of text visible only to "JOE" from domain "192.1.", we could not use...
<HIDE><SHOW_USERNAME JOE> <SHOW_DOMAIN 192.1.> This text would be visible to "JOE" and to users coming from "192.1"!
In this case, as long as the user's name was Joe, it wouldn't matter what their domain was, because the <SHOW_DOMAIN 192.1.> command would never turn the "faucet" off. "Joe"s all over the Internet would have access to the text. Similarly, anyone at domain "192.1" would also see the text, no matter what their name.
In general, any time you have two conditions that both need to be met, you will encounter this problem. The "except" variation solves this. In this example, you could use the except variation like this...
<HIDE><SHOW_USERNAME JOE> <HIDE_DOMAIN# 192.1.> This is what we wanted! Only Joe can see this, and only if he's at 192.1.
The first part of this is simple enough... Hide text, then let "Joe" see it again. The command <HIDE_DOMAIN# 192.1.> (note the "#" character) is really saying "OK, text is on, so it's Joe. Now hide the text unless he is in the '192.1' domain".
To combine the effect of two commands to hide the HTML on Saturday between 8:00 and 9:00, use the except variation on the second command:
<SHOW><HIDE_DAY SAT><SHOW_TIME# 08>
The HIDE_DAY command will hide the HTML all day on Saturday, but the SHOW_TIME# ("show_time except") command will cancel out the effect of the HIDE_DAY except between 8:00 and 9:00. This results in the HTML being hidden only on Saturday between 8:00 and 9:00.
Another common use for this technique is with username and password commands. These commands each work on the username or password, but not both. To show based on the username and password, use:
<HIDE><SHOW_USERNAME clarus> <HIDE_PASSWORD# moof>
The SHOW_USERNAME will only show HTML following it if the username is "clarus", and the HIDE_PASSWORD# will hide it again except when the password is also "moof". This results in the HTML following the show/hide-except commands being shown only when the username and password are correct.
Finally, you can combine the power of NetCloak commands in more interesting ways, by nesting any INSERT command as a parameter inside another NetCloak command. When nesting commands, the nested INSERT command must be a separate parameter, by itself, and not enclosed in double-quotes. Here are some examples of nested commands:
Create a counter with the name of the current URL:
<INSERT_COUNT <INSERT_THISURL>>
Redirect to a user-selected URL:
<REDIRECT <INSERT_VARIABLE selectedURL>>
Insert a macro file based on the current date
<SET_LOCAL todaysMacro = "/DatedMacros/" & <INSERT_DATE SHORT>> <MACRO <INSERT_LOCAL todaysMacro>>
Here is an example that does not work, because you can only include nested commands as a complete, stand-alone, parameter:
<REDIRECT "/newPath/<INSERT_VARIABLE selectedPage>">
To achieve the desired result, you could do this:
<SET_LOCAL newURL = "/newPath/" & <INSERT_VARIABLE selectedPage>> <REDIRECT <INSERT_LOCAL newURL>>
Using Nested NetCloak commands can be tricky, and we recommend only using them when you are very familiar with how NetCloak works and the commands being used.
Copyright © 1996-7 Maxum Development Corporation
820 South Bartlett Road - Suite 104
Streamwood, IL 60107
http://www.maxum.com/